Setting up GitLab as a NuGet Package Source in Visual Studio

TLDR

• The GitLab Package Registry can serve as a private NuGet repository, allowing for automated packaging and publishing workflows via GitLab CI/CD.
• In CI/CD pipelines, you must correctly configure dotnet nuget add source and use the CI_JOB_TOKEN for authentication.
• If you encounter NU1101 errors during CI/CD, you need to expand access permissions in GitLab's "Job token permissions" settings.
• Visual Studio users must create a Personal Access Token with read_api permissions and configure credentials in the NuGet package source settings.
• If Visual Studio repeatedly prompts for credentials, check and manually fix the <packageSourceCredentials> configuration in %AppData%\NuGet\NuGet.Config.

Using GitLab Packages as a Repository

For internal company packages, it is recommended to create a dedicated GitLab group to manage package projects and utilize GitLab Packages as the package source. Since GitLab does not provide a UI for directly uploading .nupkg files, it is recommended to implement automated publishing via GitLab CI/CD.

Configuring GitLab CI/CD for Automated Publishing

Through CI/CD pipelines, you can automate the execution of dotnet pack and dotnet nuget push. Below is a recommended YAML configuration example:

image: 'mcr.microsoft.com/dotnet/sdk:8.0'

stages:
 - pack
 - publish

variables:
 NUGET_PACKAGES_DIRECTORY: '.nuget'

before_script:
 - export PROJECT_FILE=$(find . -type f -name "*.csproj" | head -n 1)
 - export PROJECT_DIR=$(dirname "$PROJECT_FILE")
 - dotnet nuget add source "${CI_API_V4_URL}/groups/${PACKAGES_GROUP_ID}/-/packages/nuget/index.json" --name gitlab-packages --username gitlab-ci-token --password ${CI_JOB_TOKEN} --store-password-in-clear-text

pack:
 stage: pack
 script:
   - dotnet pack $PROJECT_DIR --configuration Release --output $NUGET_PACKAGES_DIRECTORY
 artifacts:
   paths:
     - $NUGET_PACKAGES_DIRECTORY/*.nupkg

publish:
 stage: publish
 script:
   - dotnet nuget add source "${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab-project --username gitlab-ci-token --password ${CI_JOB_TOKEN} --store-password-in-clear-text
   - cd $NUGET_PACKAGES_DIRECTORY
   - for pkg in *.nupkg; do dotnet nuget push "$pkg" --source gitlab-project; done

Resolving CI/CD Permission Issues

When does this issue occur? When the CI/CD pipeline encounters an error NU1101: Unable to find package during dotnet restore or push.

This happens because the $CI_JOB_TOKEN is restricted to accessing packages within the current project by default. To resolve this, follow these steps:

1. Go to your GitLab project's "Settings" → "CI/CD".
2. Locate the "Job token permissions" section and click "Add group or project".
3. Add the groups or projects that need access to expand the scope of the token's permissions.

TIP

Before permissions are configured, dotnet restore will fail because it cannot resolve dependency packages, even if the token is set up correctly. Adding the --verbosity detailed parameter can help confirm if the NU1101 error is caused by insufficient permissions.

Setting up GitLab Package Source in Visual Studio

Creating an Access Token

To allow Visual Studio to read private packages, you must create a Personal Access Token:

1. Go to "Preferences" → "Access Tokens".
2. Select the read_api permission.
3. Generate and save the token securely (it is only displayed once).

Configuring Visual Studio Credentials

Add the GitLab NuGet URL in Visual Studio under "Tools" → "Options" → "NuGet Package Manager" → "Package Sources". If Visual Studio repeatedly prompts for credentials after configuration, check if %AppData%\NuGet\NuGet.Config contains the <packageSourceCredentials> block.

If the configuration file is missing the credentials, you can manually add them via the command prompt:

dotnet nuget add source "https://{GitLab Domain}/api/v4/groups/{Group ID}/-/packages/nuget/index.json" --name=GitLab --username={GitLab Username} --password={Access Token}


Changelog

• 2025-03-30 Initial version created.